Oracle Portlet Developer Kit (PDK)
Installing the PDK-Java Framework and Sample Portlet Producers

Contents

Introduction
Contents of pdk software archive
Contents of the jpdk/v2 Directory
Installing or Upgrading to This Version of PDK-Java
Manually Installing to a Stand-Alone OC4J Instance
Testing the Deployment
Registering the Sample Portlet Producers
Migrating PDK-Java Applications
Deploying Your Own Portlet Producers

Introduction

Note: Starting with PDK 9.0.4.1.0, the PDK download is intended to be installed and deployed in a standalone OC4J instance only. If you plan to use PDK in an Oracle Application Server instance, you must get and install the corresponding Oracle Application Server releases or patchsets.

Welcome to the PDK-Java. The PDK-Java Framework includes the tools and documentation to build Web portlets. This download includes the PDK-Java Framework and Web Portlet Producer Samples to help you get started. You can use the PDK-Java framework to develop your own web portlet producers and portlets. Please refer to the PDK documentation on web portlet producers for more information.

This document is an installation and configuration guide for the PDK-Java Framework and samples. It explains how to

• setup and configure a standalone OC4J (Oracle Containers for J2EE) instance to run the PDK-Java Framework.
• install and register the sample portlet producers included in this download.

Contents of pdk software archive 

The PDK-Java and sample producers are part of the Oracle Portal Developers Kit (PDK). To begin the installation process you will have already down loaded and unpackaged the pdk software archive into a directory located on the same machine as your OC4J instance. (The remainder of the instructions contained in this document will refer to this directory as $unzip_directory.) Unzipping the pdk software archive in the $unzip_directory creates the following directory structure: 

• pdk

  • jpdk/v2 (see Contents of the "jpdk/v2" Directory for more information)
• portalTools
• portlet-container

Contents of the "jpdk/v2" Directory

The jpdk/v2 directory is created under $unzip_directory/pdk and contains all the files required by the PDK-Java. The following files are included in this directory:

• installing.pdkjava.v2.html: Instructions for installing the PDK-Java (i.e., the document you are currently reading).
• migrating.to.pdkjava.904.html: Instructions for migrating existing web portlet producers from PDK-Java v1 to PDK-Java v2.
• pdkjava.v2.release.notes.html: Release notes describing changes since the last release and known issues with this release
• jpdk.ear: The enterprise archive (EAR) file for the PDK-Java Sample Portlet Producers
• doc directory: Contains portlet producer specific installation instructions. Many of the portlet producers require additional configuration before they can be registered with an Oracle Portal. There is a subdirectory for each portlet producer requiring additional configuration. The subdirectories contain the portlet producer specific configuration instructions and, in some cases, scripts or templates you will need to complete the configuration.
• template.ear: A sample EAR file you can use when packaging your own web portlet producers. See Oracle WebCenter Framework Developer's Guide for more information
• src.zip: a zip file containing the source code for public classes and interfaces you may need during the development process - either for debugging your own portlet producer or understanding more about the PDK-Java framework when creating your own implementations of abstract classes or extending the default implementations.
• pdkinstaller.jar: a utility for installing PDK-Java and Oracle Portal Tools shared libraries and for adding configuration directories for Oracle Portal Tools applications.

Installing or Upgrading to This Version of PDK-Java

Before proceeding, note the minimum supported application server versions stated in the release notes. If you want to upgrade PDK-Java applications currently deployed on older application server versions, you will need to install PDK-Java on one of the supported application server versions first, and then proceed to migrate the applications from the older application server. See the document Migrating Applications to PDK-Java Release 9.0.4 and later for details on how to do this.

Note: If your upgraded portlets had previously been invoked in Edit Defaults mode by users logged in with multiple Oracle Portal session languages, you may have to use the Preference Store Migration Utility to ensure that the appropriate locale specific portlet preferences data is visible to your upgraded portlets. See the release notes for more information on the Preference Store Migration Utility.

Manually Installing to a Stand-Alone OC4J Instance

This section assumes that you already have a stand-alone OC4J server installed and configured. If you do not have an OC4J installation, please install and configure it according to its installation instructions. 

Installing or Upgrading the PDK-Java Framework

1. Stop your OC4J instance, if it is running, using the following command:

   $ORACLE_HOME/bin/oc4j -shutdown -port <ORMI port> -password <admin_password>

2. Run the PDK installer. This will install the PDK-Java shared libraries. It will also install the Oracle Portal Tools shared libraries and configuration files. The installer is run with the following command:

   java -jar -classpath $ORACLE_HOME/lib/xmlparserv2.jar -jar pdkinstaller.jar $ORACLE_HOME/j2ee/home

   This will create jar files inside the following directories.
• $ORACLE_HOME/jlib
• $ORACLE_HOME/portal/jlib
• $ORACLE_HOME/adfp/lib
• $ORACLE_HOME/BC4J/lib
• $ORACLE_HOME/wireless/lib

If any files already exist at those locations they will not be overwritten. If you do wish to overwrite these you will need to remove them and rerun the installer. In a clean OC4J it will also create two shared libraries, oracle.portal and adf.oracle.domain. If the installer is being run in an OC4J instance which already has these libraries, for example if the JDeveloper ADF installer tool has already been run or if the PDK installer is being run more than once, the shared library definitions will not be updated.

Notes:
$ORACLE_HOME is the root directory of your OC4J installation. You will find directories named "bin", "j2ee", "javacache", "jdbc" etc. under this directory.

The installer installs a subset of the Oracle WebCenter libraries. If an OC4J instance has the PDK libraries already installed and is to be updated with the ADF installer the "oracle.portal" shared library entry should be removed from the file $ORACLE_HOME/j2ee/home/config/server.xml before the ADF installer is run, and the PDK installer should be run again afterwards.

3. PDK-Java is now installed and available to all J2EE applications deployed in this OC4J instance. Start up the OC4J server again as a background process with the following commands
   • In Windows Command Prompt:
     set OC4J_JVM_ARGS=-server -Xmx512m
     set ORACLE_HOME=<$unzip_directory>
     set JAVA_HOME=<path to java installation>
     %ORACLE_HOME%\bin\oc4j -start
   • In Unix/Linux Bourne Shell (sh):
     setenv OC4J_JVM_ARGS "-server -Xmx512m"
     setenv ORACLE_HOME <$unzip_directory>
     setenv JAVA_HOME <path to java installation>
     $ORACLE_HOME/bin/oc4j -start

   Note: the -Xmx512m option specifies a 'maximum heap size' of 512 Megabytes for the OC4J process, which is the recommended setting. However, you may raise or lower this setting to suit your application. If you encounter java.lang.OutOfMemoryError exceptions, you should raise this setting.

   Note: The <path to java installation> can be either a JDK 1.4 or a JDK 1.5 instance. However the version of the JDK used to compile the code should be the compatible with the version running the OC4J instance, or you may encounter runtime errors.

Installing the Sample Portlet Producers

The jpdk.ear file consists of two web modules whose default names are jpdk and pdkstruts.

Note: if the PDK-Java sample application (typically called "jpdk") is already installed in your target OC4J instance or you are not interested in running any of the sample portlets, you may skip this section. If you want to replace an existing PDK-Java enterprise application in your target OC4J instance, you should proceed with extreme caution, as there may be important meta data and user customization data stored under the $ORACLE_HOME/j2ee/home/applications/jpdk/jpdk/WEB-INF directory. For this reason, it is recommended that you avoid taking this step in a production environment and you always deploy to a new J2EE application with a unique name (e.g. "jpdk1") rather than redeploying on top of an existing application. You should only undeploy an old jpdk enterprise application when you are sure that all meta data has been safely transported to the new one.

The jpdk.ear file consists of two web modules whose default names are jpdk and pdkstruts. To install the sample portlet producers:

1. Ensure OC4J is running (use the command in the previous section to start it if it is not)
2. Deploy the sample enterprise application in $unzip_directory/pdk/jpdk/v2/jpdk.ear using Enterprise Manager

• Invoke Oracle Enterprise Manager using your browser and log in. For example:
  • http://your.host.com:<port>/em
• Go to the Applications tab and press the 'Deploy' button.
• Choose the jpdk.ear file to deploy. Use the first option in the Archive section to upload the file from $unzip_directory/pdk/jpdk/v2/jpdk.ear .
• Press the Next button to get to the 'Deploy: Application Attributes' page. Enter an application name, e.g. jpdk. The context root for each of the web modules may be changed at this point if required.
• Press 'Next' to get to the 'Deployment Settings' page and then 'Deploy'. The sample application uses uix tags and images for the test page. To pick these up properly the OC4J instance needs to be bounced.
• PDK-Java v2 and Sample Portlet Producers are now deployed. Please proceed to Testing the Deployment

Testing the Deployment

To test the portlet producers in the web module jpdk, access the "sample" portlet producer's test page at the following URL:

http://$host:$port/jpdk/providers/sample

where:

• $host and $port are the host name and port number of the HTTP listener for your target OC4J instance. In a standalone OC4J installation, the default HTTP port number is 8888.

This page lists the portlets that are included with the portlet producer that has a service name of "sample". The test pages of other portlet producers in the same web module can be accessed using a similar URL. Simply replace "sample" with the service name of the portlet producer.

The service names of the other portlet producers included with the PDK-Java v2 Sample Portlet Producers application are:

• sample - demonstrates many of the basic capabilities of the PDK-Java v2
  • portlet pages implemented as static HTML files
  • portlet pages implemented as JSPs
  • portlet pages implemented as Servlets
  • portlet pages implemented as Java classes
  • all portlet render modes
  • stateful or session-based portlets
  • portlets containing images
  • expires based caching
  • validation based caching
  • portlet personalization
  • parameters and events
  • private event submission
  • mobile enabled portlets
• dbPreferenceStore - demonstrates how to use a database-based Preference Store for storing personalization data
• event - demonstrates how to build portlets using parameters and events
• externalApp - demonstrates how to build a web portlet producer associated with an External Application
• feedback - demonstrates how to build a portlet that submits data to itself without that data being "seen" by other portlets
• partnerApp - demonstrates how to build a web portlet producer associated with a Partner Application
• prefStore - includes portlets demonstrating the use of the Preference Store API for storing generic data (not just personalization data). Requires configuration of a datasource and database table
• subscriber - demonstrates how to build a web portlet producer that allows Oracle Portals to subscribe to its services
• webcache - demonstrates invalidation based caching and the ESI portlets (requires Oracle Application Server)
• webservices - demonstrates how to build portlets that utilize the Web Services renderers

The majority of the producers require additional configuration of some kind. For each of these producers there is an installation document detailing the additional configuration steps and instructions for using the producer. The installation documents can be found in $unzip_directory/pdk/jpdk/v2/doc/{service name}

To test the portlet producers in the web module pdkstruts, access the "struts" portlet producer's test page at the following URL:

http://$host:$port/pdkstruts/providers/struts

This application contains a single producer which demonstrates the use of Struts tags inside PDK-Java v2 portlet producers. The documentation for the sample can be found at $unzip_directory/pdk/jpdk/v2/doc/struts.

Registering the Sample Portlet Producers with Oracle Portal 10g

After deploying the PDK-Java Sample Portlet Producers, you must register the portlet producer with Oracle Portal before adding the sample portlet(s) to a page.

1. Log in to Oracle Portal using an account that has build privileges. If your home page is not the "build/administer" page, click on the Builder link in the top right corner of the screen. Click on the Build tab if that is not the active tab.
2. Under the Build tab (on the Oracle Portal Home Page), click on Register Portlet Provider within the portlet called Providers.
3. Fill out portlet producer information for the sample.
   • Name: SampleWebProvider
   • Display Name: Sample Web Provider
   • Timeout: 100
   • Timeout Message: Application Timed Out
   • Implementation Style: Web
4. Click on the next button to enter the web portlet producer specific information
5. Enter the web portlet producer location and Service Name
• URL: http://$host:$port/jpdk/providers
• Service Name: urn:sample
6. Scroll down to the User/Session Information section and specify the login frequency
   • Login Frequency: Once Per User Session
7. Click on the Finish button to complete the registration

Note: When registering a new portlet producer with Oracle Portal, only the user who registered the portlet producer has privileges to see the portlet producer or its portlets. If necessary, go to the Folder with the name of the portlet producer within the Portlet Repository content area and update the portlet producer privileges as required.

Adding Sample Portlets to an Oracle Portal Page

1. Display the contents of the Portlet Repository and review the sample portlets.

2. Add any of the sample portlets listed under the portlet producer called "SampleWebProvider" to an Oracle Portal page.

   Please refer to Oracle Portal online documentation for more information on adding portlets to a page.

Registering and Adding Portlets to a Page using Oracle AS 10gR3(10.1.3.2.0)

Having installed the Oracle PDK-Java Framework and samples you can now:

• Add portlets to an Oracle Portal page (refer to the Oracle WebCenter Framework Developer's Guide for guidelines)
• Begin building your own PDK-Java portlets. (Use the Oracle PDK-Java Portlet Wizard or refer to the Oracle WebCenter Framework Developer's Guide for detailed information on building Oracle PDK-Java portlets.)

Migrating PDK-Java Applications

Deploying Your Own Web Portlet Producers

Review the Oracle WebCenter Framework Developer's Guide for detailed instructions on how to package and deploy your own portlet producers and also for detailed information regarding creating new portlet producers.